Skip to content

Context v2: name the binding, show the measurement, stop the false URL - #21

Merged
scottypate merged 1 commit into
mainfrom
context-v2-bindings-and-measurements
Aug 11, 2026
Merged

Context v2: name the binding, show the measurement, stop the false URL#21
scottypate merged 1 commit into
mainfrom
context-v2-bindings-and-measurements

Conversation

@scottypate

Copy link
Copy Markdown
Contributor

From a design partner consuming a live bound cell. Four document changes, one breaking, plus the OpenAPI surface that let two of them go unnoticed.

  • declared.exports[].binding {source, object, connection}, present iff query is null. A bound export's target existed only in docs prose and data.channels' operator hints, so writing a query against a cell that serves no rows meant reading English. Values are verbatim cell.yaml, never profile-resolved: table is env-expandable and Declared is hashed into interface_digest, so a resolved value would fold the environment into the digest.
  • observed.source_check.exports[route] {check, grain, rows, distinct_grain}. verify::grain_counts computed the numbers behind grain_verified, compared them, and discarded them. Persisted through .cell/source_check.json under the record's existing digest+profile gate, visibility-filtered on the way to the wire. A grainless export contributes no entry — no check ran on it.
  • MeshExport.bound, so an agent routing off the manifest stops picking an export that 404s. The emitter accepts datamk_context 1 or 2.
  • declared.docs[].path -> source_path, which is why datamk_context is 2. A cell.yaml-relative path named path in a JSON document served over HTTP reads as a relative URL and 404s — the same false affordance already corrected for route.

/context's 200 had no schema at all, so nothing said include= content lands at a top-level key named for the section rather than inside included (which holds section names). It has one now, pinned to ContextDocument's keys by a test. Data path items carry x-datamk-version and x-datamk-contract, previously prose inside summary.

Declined, with reasoning in the ADR: a cell-level semver (no cell version exists; it would drift from the per-export semvers) and a structured caveats array (free-text rule + unenforced severity is prose in a JSON wrapper, drifting like source_descriptions already does). The hazard caveats aimed at — two USD columns that must not be subtracted — stays open; the only fix that isn't docs-in-JSON is a typed column property the engine can verify.

From a design partner consuming a live bound cell. Four document changes,
one breaking, plus the OpenAPI surface that let two of them go unnoticed.

- declared.exports[].binding {source, object, connection}, present iff
  `query` is null. A bound export's target existed only in docs prose and
  `data.channels`' operator hints, so writing a query against a cell that
  serves no rows meant reading English. Values are verbatim cell.yaml,
  never profile-resolved: `table` is env-expandable and `Declared` is
  hashed into interface_digest, so a resolved value would fold the
  environment into the digest.
- observed.source_check.exports[route] {check, grain, rows,
  distinct_grain}. verify::grain_counts computed the numbers behind
  `grain_verified`, compared them, and discarded them. Persisted through
  .cell/source_check.json under the record's existing digest+profile gate,
  visibility-filtered on the way to the wire. A grainless export
  contributes no entry — no check ran on it.
- MeshExport.bound, so an agent routing off the manifest stops picking an
  export that 404s. The emitter accepts datamk_context 1 or 2.
- declared.docs[].path -> source_path, which is why datamk_context is 2.
  A cell.yaml-relative path named `path` in a JSON document served over
  HTTP reads as a relative URL and 404s — the same false affordance
  already corrected for `route`.

/context's 200 had no schema at all, so nothing said include= content
lands at a top-level key named for the section rather than inside
`included` (which holds section names). It has one now, pinned to
ContextDocument's keys by a test. Data path items carry x-datamk-version
and x-datamk-contract, previously prose inside `summary`.

Declined, with reasoning in the ADR: a cell-level semver (no cell version
exists; it would drift from the per-export semvers) and a structured
`caveats` array (free-text rule + unenforced severity is prose in a JSON
wrapper, drifting like source_descriptions already does). The hazard
caveats aimed at — two USD columns that must not be subtracted — stays
open; the only fix that isn't docs-in-JSON is a typed column property the
engine can verify.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@scottypate
scottypate merged commit bd25a9c into main Aug 11, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant